package com.starview.platform.data;

public interface IExtensibleRelation extends IRelation
{
  /**
   * Add a new tuple to the relation.
   * 
   * @param tuple
   *          the new tuple in the relation. No check is implied to see if there is already an
   *          equivalent tuple in the relation.
   * @return the new relation that results
   */
  IExtensibleRelation addCell(IValue tuple) throws EvaluationException;

  /**
   * Concatenate a relation to the relation
   * 
   * @param sub
   *          the list to merge with this relation
   * @return
   * @throws EvaluationException
   */
  IExtensibleRelation concat(IRelation sub) throws EvaluationException;

  /**
   * Remove a tuple from the relation. This relies on the use of equals to remove the entry; so if a
   * relation has multiple copies of a value, the effect is undefined
   * 
   * @param tuple
   *          the tuple to remove from the relation
   * @return the relation minus the tuple
   * @throws EvaluationException
   *           if a problem arises during the attempt to remove.
   */
  IExtensibleRelation removeCell(IValue tuple) throws EvaluationException;

  /**
   * Replace an entry that matches old with a new replacement.
   * 
   * @param old
   * @param repl
   * @return a new relation
   */
  IExtensibleRelation replaceCell(IValue old, IValue repl) throws EvaluationException;

  /**
   * remove all elements from a relation that match a given pattern
   * 
   * @param filter
   * @return the modified relation
   * @throws EvaluationException
   */
  IExtensibleRelation deleteUsingPattern(IPattern filter) throws EvaluationException;

  /**
   * Replace elements that match a pattern with new elements
   * 
   * @param filter
   * @param transform
   * @return
   * @throws EvaluationException
   */
  IExtensibleRelation updateUsingPattern(IPattern filter, IFunction transform) throws EvaluationException;
}